Inside Macintosh: AppleScript Language Guide / Part 2 - AppleScript Language Reference

Chapter 7 - Control Statements / Try Statements

Signaling Errors in Scripts

Error

The Error command signals an error in a script.

SYNTAX

error                         ¬
   [ errorMessage ]           ¬
   [ number errorNumber ]     ¬
   [ from offendingObject ]   ¬
   [ partial result resultList ] ¬
   [ to expectedType ]

where

errorMessage is an expression, usually a string, describing the error. Although this parameter is not required, you should provide descriptive expressions
for errors wherever possible (a string is the best way to inform the user of an error), and you should always provide an expression if you do not include a number parameter. If you do not include an error expression, an empty string ("") is passed to the error handler.

errorNumber is the error number for the error. You do not have to include an error number, but if you do, the number must not be any of the error numbers listed in Appendix C, "Error Messages." In general, positive numbers from 500 to 10,000 do not conflict with error numbers for AppleScript, the Operating System, or Apple events. If you do not include a number parameter, the value -2700 is passed to the error handler.

offendingObject is a reference to the object, if any, that caused the error. If you provide a partial reference, AppleScript completes it using the value of the default object.

resultList applies only to commands that return results for multiple objects. If results for some, but not all, of the objects specified in the command are available, you can include them in the partial result parameter. If you do not include a partial result parameter, an empty list ({}) is passed to the error handler.

expectedType is a class identifier. If a parameter specified in the command was not of the expected class, and AppleScript was unable to coerce it to the expected class, then you can include the expected class in the to parameter.

EXAMPLES

The following example shows how to signal and provide a handler for an error. The CentimeterConversion subroutine signals error number 750 if its parameter is not a number. The error handler tests the error number, and if it
is equal to 750, returns a string indicating that the parameter must be a real number or integer.

on CentimeterConversion from x
   --make sure the parameter is a real number or an integer
   try
      if {integer, real} contains class of x then
         return x * 2.54
      else
         error number 750
      end if
   on error number errorNumber
      if errorNumber = 750 then
         return "The parameter must be a real number or integer."      else
         error errorNumber --unknown error, resignal
      end if
   end try
end CentimeterConversion

CentimeterConversion from "Cupertino"--result: "The parameter must be a real number or integer."

You can use the Error command to resignal an error. For example, in the following Try statement, the Error command in the error handler resignals
the error exactly as it was received.

try
   word 5 of "one two three"on error number errNum from badObj
   --statements that handle the error
   error number errNum from badObj
end try

In the following Try statement, the Error command in the error handler resignals the error, but changes the error message and error number. The
new error number is 600.

try
   word 5 of "one two three"on error
   --statements that determine the cause of the error
   error "There are not enough words." number 600
end try